{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# Markdown Cells\n", "\n", "## Try me\n", "[![Open In Colab](../../_static/colabs_badge.png)](https://colab.research.google.com/github/ffraile/computer_science_tutorials/blob/main/source/Introduction/tutorials/Working%20with%20Markdown%20cells.ipynb)[![Binder](../../_static/binder_badge.png)](https://mybinder.org/v2/gh/ffraile/computer_science_tutorials/main?labpath=source%2FIntroduction%2Ftutorials%2FWorking%20with%20Markdown%20cells.ipynb)\n", "\n", "Text can be added to IPython Notebooks using **Markdown cells**. Markdown is a popular **markup language**. In this context, markup refers to the information used to control how the document must be presented, rather than the content of the document itself. Markdown is therefore a **descriptive language** in the sense that we use the markup specification to control how text is presented and do not worry how the web browser actually renders it. Markdown is a superset of the HyperText Markup Language [HTML](https://en.wikipedia.org/wiki/HTML) which is used to build web pages, and in that sense, you will find that you can create the same type of documents you find over the Internet using Markdown. The specification can be found here:\n", "\n", "\n", "\n", "> ☝ Since you can view the source of a cell just by double-clicking on it, this guide is basically build using examples, and you can check the code just by clicking on the cell or while the cell is selected in command mode, press `Enter` to edit it. Once a cell has been edited, use `Shift-Enter` to re-render it." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Markdown basics\n", "### Code blocks\n", "You can enter block codes in Markdown cells surrounding the text you want to display as code using triple quotes (````) and adding the language name. For instance, the following code block will display some python code styled using Python language syntax:\n", "\n", "```python\n", "# This is a comment\n", "print(\"Hello, world!\")\n", "```\n", "\n", "Note that you cannot execute the code in a markdown cell, but still, you can render the code in the web-browser. This is convenient to write documentation for your code embedded in the Markdown cell, or to explain bits of code written in a programming language not supported by the Notebook Kernel (e.g. SQL).\n", "\n", "> ☝ In this Notebook, we will use code blocks with the `Markdown` language name so that we can render Markdown syntax in the web-browser. Keep this in mind when you check the source code of the Markdown cells below!\n", "\n", "\n", "### Bold text and italics\n", "You can make text *italic* or **bold**, surrounding the text with either '*' or double '**'. For instance, the code:\n", "\n", "```markdown\n", "*italics*\n", "```\n", "\n", "will write down the word 'italics' in italics, and the code:\n", "\n", "```markdown\n", "**bold text**\n", "```\n", "\n", "will write the text 'bold text' in bold." ] }, { "cell_type": "markdown", "source": [ "### Headings\n", "You can use the `#` character to create a heading. For instance, the code:\n", "\n", "```markdown\n", "# This is a heading\n", "```\n", "Creates a heading with the text 'This is a heading'. Headings are organized in levels, with level 1 being the largest and level 6 the smallest. Therefore, the code:\n", "\n", "```markdown\n", "#### 1.1.1.1 Heading level 4 example\n", "This is a paragraph in the heading level 4 example.\n", "\n", "### 1.1.1.1.1 Heading level 5 example\n", "This is a paragraph in the heading level 5 example.\n", "```\n", "will create styled headings of level 4 and 5." ], "metadata": { "collapsed": false } }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Lists\n", "\n", "You can build itemized lists using the `-` character, and nested sub-lists using the tabulator or insert some spaces before the `-` character. For instance, the code:\n", "\n", "```markdown\n", "- Item list number one\n", " - Sublist number one\n", " - This is a sublist item\n", " - Sublist number two\n", " - This is a sublist item\n", " - And this is another\n", "- Item list number two\n", " - This is another sublist item\n", " - Here, just one more sublist:\n", " - One item\n", " - And one more!\n", "```\n", "Creates the following list:\n", "\n", "- Item list number one\n", " - Sublist number one\n", " - This is a sublist item\n", " - Sublist number two\n", " - This is a sublist item\n", " - And this is another\n", "- Item list number two\n", " - This is another sublist item\n", " - Here, just one more sublist:\n", " - One item\n", " - And one more!\n", "\n", "You can also create numbered nested lists just using numbers before a '.' character. For instance:\n", "\n", "```markdown\n", "1. Here we go\n", " 1. Sublist item 1\n", " 2. Sublist item 2\n", "2. Here we go again\n", " 1. Sublist item 1\n", " 2. Sublist item 2\n", "```\n", "\n", "Will create this sublist:\n", "1. Here we go\n", " 1. Sublist item 1\n", " 2. Sublist item 2\n", "2. Here we go again\n", " 1. Sublist item 1\n", " 2. Sublist item 2" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Additional Markdown syntax\n", "While we covered the basics on the section above, this section includes some syntax tips that you can use to enhance the presentation of your document.\n", "\n", "### Horizontal rules\n", "Horizontal rules introduce a horizontal separator in your document, for instance: For instance, the code:\n", "\n", "```markdown\n", "---\n", "```\n", "will create a horizontal rule like this:\n", "\n", "---" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Block quotes\n", "Block quotes are handy to highlight some text. For instance, the code:\n", "\n", "```markdown\n", "> **Ben Parker**: With great power comes great responsibility.\n", "```\n", "will generate the following block quote:\n", "\n", "> **Ben Parker**: With great power comes great responsibility." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Inline links\n", "You can create links to other pages or to external resources using the following syntax:\n", "\n", "```markdown\n", "This is a link to [IPython's website](https://ipython.org)\n", "```\n", "\n", "will create the following link:\n", "\n", "This is a link to [IPython's website](https://ipython.org)\n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Inline images\n", "You can insert images in your Markdown document using the following syntax:\n", "\n", "```markdown\n", "![alternative text](https://ipython.org/_static/IPy_header.png \"Title: Logo\")\n", "```\n", "\n", "![alternative text](https://ipython.org/_static/IPy_header.png \"Title: Logo\"){width=50%}\n", "\n", "Note that syntax includes an alternative text for the image, which is used when the image is not displayed (for instance when the content is transcribed by a screen reader). It is important to include a rich description of your image in the alternative text, so that it can be used by screen readers.\n", "\n", "### Images with links\n", "You can also insert images with links. For instance, the code:\n", "\n", "```markdown\n", "[![alternative text](https://ipython.org/_static/IPy_header.png \"Title: Logo\")](https://ipython.org)\n", "```\n", "inserts an image that links to the iPython website, as shown below:\n", "\n", "[![alternative text](https://ipython.org/_static/IPy_header.png \"Title: Logo\"){width=50%}](https://ipython.org)\n", "\n", "Note that basically, the only differences between previous examples is that we wrapped the image in the link description!" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## LaTeX equations\n", "\n", "You can include mathematical expressions using LaTex notation wrapped using the dollar symbol as a delimiter. You can insert equations inline (in the same line) as text like:\n", "\n", "```markdown\n", "This is an inline equation $e^{i\\pi} + 1 = 0$\n", "````\n", "\n", "This is an inline equation $e^{i\\pi} + 1 = 0$\n", "\n", "You can also use the dollar symbol to include equations standalone in a new line. For instance, the code:\n", "\n", "```markdown\n", "$$e^x=\\sum_{i=0}^\\infty \\frac{1}{i!}x^i$$\n", "```\n", "Will introduce an equation in a new line, like this:\n", "\n", "$$e^x=\\sum_{i=0}^\\infty \\frac{1}{i!}x^i$$\n", "\n", "\n", "### Latex cheat sheet\n", "You can find a comprehensive cheat sheet for LaTeX equations [here](https://github.com/DonneyF/MATH217FormulaSheet). You can also use [Overleaf](https://www.overleaf.com) to find tutorials and edit equations online. However, we hope this table contains the most common LaTeX commands and symbols.\n", "\n", "| Symbol | LaTex Command | Description | Example |\n", "|---------------|---------------|-----------------------------------------------------------------------------------------|-----------------------|\n", "| $x^y$ | ```^{x}``` | Exponent. The expression in the exponent is passed between **curly brackets ({})** | $x^{y+1}$ |\n", "| $x_i$ | ```_{i}``` | Subscript. The expression in the subscript is passed between curly brackets | $x_{i+1}$ |\n", "| $\\sum$ | ```\\sum``` | Summation. You can add subscripts and exponents to determine the range of the summation | $\\sum_{i=0}^{10}{i!}$ |\n", "| $\\frac{x}{y}$ | ```\\frac``` | Fraction. Pass first the numerator and then the denominator using curly brackets | $\\frac{1}{2}$ |\n", "| $\\int$ | ```\\int``` | Integration. Pass the expression to integrate and the variable to integrate over | $\\int x^2 dx$ |\n", "| $\\sqrt{x}$ | ```\\sqrt``` | Square root. Pass the expression to square root using curly brackets | $\\sqrt{x^2}$ |\n", "| $\\geq$ | ```\\geq``` | Greater than or equal to. | $\\geq x^2 dx$ |\n", "| $\\leq$ | ```\\leq``` | Less than or equal to. | $\\leq x^2 dx$ |\n", "| $\\neq$ | ```\\neq``` | Not equal to. | $\\neq x^2 dx$ |\n", "| $\\alpha$ | ```\\alpha``` | Any greek symbol, using its english name (e.g. alpha). | $\\alpha$ |\n", "| $\\beta$ | ```\\beta``` | Beta is another popular greek symbol. | $\\beta$ |\n", "| $\\gamma$ | ```\\gamma``` | Gamma is another great greek symbol. | $\\gamma$ |\n", "| $\\omega$ | ```\\omega``` | But Omega as in Omega level mutant is my favourite. | $\\omega$ |\n", "\n", "### Matrices and vectors in LaTeX\n", "You can just use brackets to insert vectors in LaTex, which is quite convenient. For instance, the code:\n", "\n", "```markdown\n", "x = [1, 2, 3]\n", "```\n", "\n", "Defines a row vector x with the values 1, 2, 3.\n", "\n", "Writing a matrix in LaTex is a bit more complicated. You can use the following syntax:\n", "\n", "```markdown\n", "\\begin{bmatrix}\n", " 1 & 2 & 3 \\\\\n", " 4 & 5 & 6 \\\\\n", " 7 & 8 & 9\n", "\\end{bmatrix}\n", "```\n", "To write a matrix like:\n", "\n", "\\begin{bmatrix}\n", " 1 & 2 & 3 \\\\\n", " 4 & 5 & 6 \\\\\n", " 7 & 8 & 9\n", "\\end{bmatrix}\n", "\n", "\n", "Note that we write the matrix row-by-row, using two backslashes to separate rows, and the **&** symbol to separate cells in a row." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Tables\n", "\n", "You can add a table like this in your document:\n", "\n", "```markdown\n", "| This | is |\n", "|------|------|\n", "| a | table|\n", "```\n", "\n", "will display the following table:\n", "\n", "| This | is |\n", "|------|-------|\n", "| a | table |\n", "\n", "The table cells are delimited by the (|) character. The first row and first column are used to determine the width of the table, so it is important to insert spaces if you want to control the table width and text alignment across the table. Also, note that the first row is used as headers, and that there is a separator between the header and the table body.\n", "\n", "Note that the text in the table is automatically aligned to the left. You can control the alignment of the text using colons (```:```) after the column delimiter. For instance, the code:\n", "\n", " ```markdown\n", " | Right aligned |centered aligned |\n", " |----------------------------------:|:------------------------:|\n", " | This is a right aligned column | and this one is centered |\n", " ```\n", "\n", "see:\n", "\n", "\n", "| Right aligned | centered aligned |\n", "|-------------------------------:|:------------------------:|\n", "| This is a right aligned column | and this one is centered |\n", "\n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Local files\n", "\n", "If you have local files in your Notebook directory, you can refer to these files in Markdown cells directly:\n", "\n", " [subdirectory/]\n", "\n", "For example, you can use this feature to include images that are not publicly available on the internet, but in your local directory. Say you have an image named ```my_image.png``` in a folder named ```images``` your notebook directory. You can then use the following code to include this image in your Markdown document:\n", "```\n", " ![my_image.png](images/my_image.png)\n", "```\n", "\n", "You can also embed a video and video controls with the HTML5 video tag:\n", "\n", "```HTML\n", "